feat(ns-api): add live trace troubleshooting API - #2007

When a client cannot reach something, administrators have to guess which part of the firewall is blocking it. Live trace follows one client IP address for a limited time and reports which layer stopped each new connection: a firewall rule or zone policy, Threat Shield IP (banIP) block lists, DPI (deep packet inspection) rules, the DNS filter or MAC binding. It also lists the client's DNS queries with their result and whether the DNS filter blocks them, its live connections, and routing hints such as a private address sent out to the WAN or a destination with no route.

The new ns.livetrace API (start, stop, status) starts a background collector that marks the first packet of each new connection of the client with nftables tracing, reads the verdicts from nft monitor trace and DNS traffic from tcpdump, and writes the results to a state file. Sessions last 10 to 600 seconds, can be filtered by port and protocol, are rate limited, and clean up their nft table and helper processes when they end. The collector reloads its view of the rules when the firewall, banIP or DPI configuration changes during a session. Methods and limitations are documented in packages/ns-api/README.md.

The commit chore(ns-ui): TEMP build UI from live trace branch builds the UI from the nethsecurity-ui firewall_debug branch, which holds the live trace page, so the image can be tested end to end. It must be dropped before merging.

How to test

• Start a session for a LAN client: api-cli ns.livetrace start --data '{"ip": "192.168.100.238", "duration": 120}'
• From the client, open connections blocked by a firewall rule, by a Threat Shield IP block list entry and by a DPI block rule, and query a domain blocked by the DNS filter
• api-cli ns.livetrace status lists each blocked connection with its layer, chain and rule name, the DNS queries with filtered set for the blocked domain, and the open connections
• Reload the firewall (fw4 reload) or restart banIP during the session: connections opened afterwards still show the right rule name
• api-cli ns.livetrace stop, then status lists the allowed connections of the session with the rule that accepted them; no ns_livetrace nft table, nft monitor or tcpdump process is left

See also

• feat(monitoring): add live trace page nethsecurity-ui#854

Generated by Claude Code:claude-opus-5-5 with nethserver-pr